1# Distributors Tutorial
2
3<!-- TOC -->
4
5## Distributors
6
7Distributors are modules that are useful for placing multiple copies of a
8child across a line, area, volume, or ring. Many transforms have one or
9more distributive variation.
10
11Transforms | Related Distributors
12----------------------- | ---------------------
13`left()`, `right()` | `xcopies()`
14`fwd()`, `back()` | `ycopies()`
15`down()`, `up()` | `zcopies()`
16`move()`, `translate()` | `move_copies()`, `line_copies()`, `grid_copies()`
17`xrot()` | `xrot_copies()`
18`yrot()` | `yrot_copies()`
19`zrot()` | `zrot_copies()`
20`rot()`, `rotate()` | `rot_copies()`, `arc_copies()`
21`xflip()` | `xflip_copy()`
22`yflip()` | `yflip_copy()`
23`zflip()` | `zflip_copy()`
24`mirror()` | `mirror_copy()`
25
26
27### Transform Distributors
28Using `xcopies()`, you can make a line of evenly spaced copies of a shape
29centered along the X axis. To make a line of 5 spheres, spaced every 20
30units along the X axis, do:
31```openscad-2D
32include <BOSL2/std.scad>
33xcopies(20, n=5) sphere(d=10);
34```
35Note that the first expected argument to `xcopies()` is the spacing argument,
36so you do not need to supply the `spacing=` argument name.
37
38Similarly, `ycopies()` makes a line of evenly spaced copies centered along the
39Y axis. To make a line of 5 spheres, spaced every 20 units along the Y
40axis, do:
41```openscad-2D
42include <BOSL2/std.scad>
43ycopies(20, n=5) sphere(d=10);
44```
45
46And, `zcopies()` makes a line of evenly spaced copies centered along the Z axis.
47To make a line of 5 spheres, spaced every 20 units along the Z axis, do:
48```openscad-3D
49include <BOSL2/std.scad>
50zcopies(20, n=5) sphere(d=10);
51```
52
53If you don't give the `n=` argument to `xcopies()`, `ycopies()` or `zcopies()`,
54then it defaults to 2 (two) copies. This actually is the most common usage:
55```openscad-2D
56include <BOSL2/std.scad>
57xcopies(20) sphere(d=10);
58```
59
60```openscad-2D
61include <BOSL2/std.scad>
62ycopies(20) sphere(d=10);
63```
64
65```openscad-3D
66include <BOSL2/std.scad>
67zcopies(20) sphere(d=10);
68```
69
70If you don't know the spacing you want, but instead know how long a line you
71want the copies distributed over, you can use the `l=` argument instead of
72the `spacing=` argument:
73```openscad-2D
74include <BOSL2/std.scad>
75xcopies(l=100, n=5) sphere(d=10);
76```
77
78```openscad-2D
79include <BOSL2/std.scad>
80ycopies(l=100, n=5) sphere(d=10);
81```
82
83```openscad-3D
84include <BOSL2/std.scad>
85zcopies(l=100, n=5) sphere(d=10);
86```
87
88If you don't want the line of copies centered on the origin, you can give a
89starting point `sp=`, and the line of copies will start there. For `xcopies()`,
90the line of copies will extend to the right of the starting point.
91```openscad-2D
92include <BOSL2/std.scad>
93xcopies(20, n=5, sp=[0,0,0]) sphere(d=10);
94```
95
96For `ycopies()`, the line of copies will extend to the back of the starting point.
97```openscad-2D
98include <BOSL2/std.scad>
99ycopies(20, n=5, sp=[0,0,0]) sphere(d=10);
100```
101
102For `zcopies()`, the line of copies will extend upwards from the starting point.
103```openscad-3D
104include <BOSL2/std.scad>
105zcopies(20, n=5, sp=[0,0,0]) sphere(d=10);
106```
107
108If you need to distribute copies along an arbitrary line, you can use the
109`line_copies()` command. You can give both the direction vector and the spacing
110of the line of copies with the `spacing=` argument:
111```openscad-3D
112include <BOSL2/std.scad>
113line_copies(spacing=(BACK+RIGHT)*20, n=5) sphere(d=10);
114```
115
116With the `p1=` argument, you can specify the starting point of the line:
117```openscad-3D
118include <BOSL2/std.scad>
119line_copies(spacing=(BACK+RIGHT)*20, n=5, p1=[0,0,0]) sphere(d=10);
120```
121
122If you give both `p1=` and `p2=`, you can nail down both the start and
123endpoints of the line of copies:
124```openscad-2D
125include <BOSL2/std.scad>
126line_copies(p1=[0,100,0], p2=[100,0,0], n=4)
127 sphere(d=10);
128```
129
130The `grid_copies()` command will let you spread copies across both the X and Y
131axes at the same time:
132```openscad-2D
133include <BOSL2/std.scad>
134grid_copies(20, n=6) sphere(d=10);
135```
136
137The spacing can be separately specified for both the X and Y axes, as can
138the count of rows and columns:
139```openscad-2D
140include <BOSL2/std.scad>
141grid_copies([20,30], n=[6,4]) sphere(d=10);
142```
143
144Another neat trick of `grid_copies()`, is that you can stagger the output:
145```openscad-2D
146include <BOSL2/std.scad>
147grid_copies(20, n=[12,6], stagger=true) sphere(d=10);
148```
149
150You can get the alternate stagger pattern if you set `stagger="alt"`:
151```openscad-2D
152include <BOSL2/std.scad>
153grid_copies(20, n=[12,6], stagger="alt") sphere(d=10);
154```
155
156By default, if you give a scalar for the spacing value, staggering will give
157you a hexagonal grid, with the spacing being the distance from an item to all
158six of the surrounding items. If you give the spacing as a 2-item vector,
159then that will force the X and Y spacings between columns and rows instead.
160```openscad-2D
161include <BOSL2/std.scad>
162grid_copies([20,20], n=6, stagger=true) sphere(d=10);
163```
164
165You can alternately specify a grid using size and spacing:
166```openscad-2D
167include <BOSL2/std.scad>
168grid_copies(20, size=100) sphere(d=10);
169```
170
171```openscad-2D
172include <BOSL2/std.scad>
173grid_copies(20, size=[100,80]) sphere(d=10);
174```
175
176```openscad-2D
177include <BOSL2/std.scad>
178grid_copies(20, size=[100,80], stagger=true) sphere(d=10);
179```
180
181You can also make grids by specifying size and column/row count:
182```openscad-2D
183include <BOSL2/std.scad>
184grid_copies(n=5, size=100) sphere(d=10);
185```
186
187```openscad-2D
188include <BOSL2/std.scad>
189grid_copies(n=[4,5], size=100) sphere(d=10);
190```
191
192```openscad-2D
193include <BOSL2/std.scad>
194grid_copies(n=[4,5], size=[100,80]) sphere(d=10);
195```
196
197Finally, the `grid_copies()` command will let you give a polygon or region shape
198to fill with items. Only the items in the grid whose center would be inside
199the polygon or region will be created. To fill a star shape with items, you
200can do something like:
201```openscad-3D
202include <BOSL2/std.scad>
203poly = [for (i=[0:11]) polar_to_xy(50*(i%2+1), i*360/12-90)];
204grid_copies(5, stagger=true, inside=poly) {
205 cylinder(d=4,h=10,spin=90,$fn=6);
206}
207```
208
209
210### Rotational Distributors
211You can make six copies of a cone, rotated around a center:
212```openscad-3D
213include <BOSL2/std.scad>
214zrot_copies(n=6) yrot(90) cylinder(h=50,d1=0,d2=20);
215```
216
217To Be Completed
218
219